From 6374226d6b2f49f88a3e526c03f9b0f968043dd8 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 26 Dec 2017 14:04:12 -0500 Subject: [PATCH] Add documentation for content (de)serializers --- gdk/gdkcontentdeserializer.c | 62 +++++++++++++++++++++++++++++++++--- gdk/gdkcontentdeserializer.h | 14 ++++++++ gdk/gdkcontentserializer.c | 59 ++++++++++++++++++++++++++++++++++ gdk/gdkcontentserializer.h | 14 ++++++++ 4 files changed, 145 insertions(+), 4 deletions(-) diff --git a/gdk/gdkcontentdeserializer.c b/gdk/gdkcontentdeserializer.c index 91c5d6e0fb..627308a695 100644 --- a/gdk/gdkcontentdeserializer.c +++ b/gdk/gdkcontentdeserializer.c @@ -30,11 +30,11 @@ /** * SECTION:gdkcontentdeserializer * @Short_description: Deserialize content for transfer - * @Title: GdkContentSerializer - * @See_also: #GdkContentDeserializer + * @Title: GdkContentDeserializer + * @See_also: #GdkContentSerializer * - * A GdkContentDeserializer is used to deserialize content for inter-application - * data transfers. + * A GdkContentDeserializer is used to deserialize content received via + * inter-application data transfers. */ typedef struct _Deserializer Deserializer; @@ -366,6 +366,17 @@ gdk_content_deserializer_return_error (GdkContentDeserializer *deserializer, gdk_content_deserializer_return_success (deserializer); } +/** + * gdk_content_register_deserializer: + * @mime_type: the mime type which the function can deserialize from + * @type: the type of objects that the function creates + * @deserialize: the callback + * @data: data that @deserialize can access + * @notify: destroy notify for @data + * + * Registers a function to create objects of a given @type from + * a serialized representation with the given mime type. + */ void gdk_content_register_deserializer (const char *mime_type, GType type, @@ -415,6 +426,15 @@ lookup_deserializer (const char *mime_type, return NULL; } +/** + * gdk_content_formats_union_deserialize_gtypes: + * @formats: a #GdkContentFormats + * + * Add GTypes for mime types in @formats for which deserializers are + * registered. + * + * Return: a new #GdkContentFormats + */ GdkContentFormats * gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats) { @@ -441,6 +461,15 @@ gdk_content_formats_union_deserialize_gtypes (GdkContentFormats *formats) return gdk_content_formats_builder_free (builder); } +/** + * gdk_content_formats_union_deserialize_mime_types: + * @formats: a #GdkContentFormats + * + * Add mime types for GTypes in @formats for which deserializers are + * registered. + * + * Return: a new #GdkContentFormats + */ GdkContentFormats * gdk_content_formats_union_deserialize_mime_types (GdkContentFormats *formats) { @@ -478,6 +507,20 @@ deserialize_not_found (GdkContentDeserializer *deserializer) gdk_content_deserializer_return_error (deserializer, error); } +/** + * gdk_content_deserialize_async: + * @stream: a #GInputStream to read the serialized content from + * @mime_type: the mime type to deserialize from + * @type: the GType to deserialize from + * @io_priority: the io priority of the operation + * @cancellable: (nullable): optional #GCancellable object + * @callback: (scope async): callback to call when the operation is done + * @user_data: (closure): data to pass to the callback function + * + * Read content from the given input stream and deserialize it, asynchronously. + * When the operation is finished, @callback will be called. You can then + * call gdk_content_deserialize_finish() to get the result of the operation. + */ void gdk_content_deserialize_async (GInputStream *stream, const char *mime_type, @@ -506,6 +549,17 @@ gdk_content_deserialize_async (GInputStream *stream, user_data); } +/** + * gdk_content_deserialize_finish: + * @result: the #GAsyncResult + * @value: return location for the result of the operation + * @error: return location for an error + * + * Finishes a content deserialization operation. + * + * Returns: %TRUE if the operation was successful. In this case, @value is set. + * %FALSE if an error occurred. In this case, @error is set + */ gboolean gdk_content_deserialize_finish (GAsyncResult *result, GValue *value, diff --git a/gdk/gdkcontentdeserializer.h b/gdk/gdkcontentdeserializer.h index b08d4983a3..d0fc4ccdba 100644 --- a/gdk/gdkcontentdeserializer.h +++ b/gdk/gdkcontentdeserializer.h @@ -32,8 +32,22 @@ G_BEGIN_DECLS #define GDK_CONTENT_DESERIALIZER(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_CONTENT_DESERIALIZER, GdkContentDeserializer)) #define GDK_IS_CONTENT_DESERIALIZER(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_CONTENT_DESERIALIZER)) +/** + * GdkContentDeserializer: + * + * Should not be accessed directly. + */ typedef struct _GdkContentDeserializer GdkContentDeserializer; +/** + * GdkContentDeserializeFunc: + * @deserializer: a #GdkContentDeserializer + * + * The type of a function that can be registered with gdk_content_register_deserializer(). + * When the function gets called to operate on content, it can call functions on the + * @deserializer object to obtain the mime type, input stream, user data, etc. for its + * operation. + */ typedef void (* GdkContentDeserializeFunc) (GdkContentDeserializer *deserializer); GDK_AVAILABLE_IN_3_94 diff --git a/gdk/gdkcontentserializer.c b/gdk/gdkcontentserializer.c index f92789b5d7..ff2267868a 100644 --- a/gdk/gdkcontentserializer.c +++ b/gdk/gdkcontentserializer.c @@ -39,6 +39,12 @@ * data transfers. */ +/** + * GdkContentSerializer: + * + * Contains only private fields and should not be directly accessed. + */ + typedef struct _Serializer Serializer; struct _Serializer @@ -369,6 +375,17 @@ gdk_content_serializer_return_error (GdkContentSerializer *serializer, gdk_content_serializer_return_success (serializer); } +/** + * gdk_content_register_serializer: + * @type: the type of objects that the function can serialize + * @mime_type: the mime type to serialize to + * @serialize: the callback + * @data: data that @serialize can access + * @notify: destroy notify for @data + * + * Registers a function to convert objects of the given @type to + * a serialized representation with the given mime type. + */ void gdk_content_register_serializer (GType type, const char *mime_type, @@ -418,6 +435,15 @@ lookup_serializer (const char *mime_type, return NULL; } +/** + * gdk_content_formats_union_serialize_gtypes: + * @formats: a #GdkContentFormats + * + * Add GTypes for the mime types in @formats for which serializers are + * registered. + * + * Return: a new #GdkContentFormats + */ GdkContentFormats * gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats) { @@ -444,6 +470,15 @@ gdk_content_formats_union_serialize_gtypes (GdkContentFormats *formats) return gdk_content_formats_builder_free (builder); } +/** + * gdk_content_formats_union_serialize_mime_types: + * @formats: a #GdkContentFormats + * + * Add mime types for GTypes in @formats for which serializers are + * registered. + * + * Return: a new #GdkContentFormats + */ GdkContentFormats * gdk_content_formats_union_serialize_mime_types (GdkContentFormats *formats) { @@ -481,6 +516,20 @@ serialize_not_found (GdkContentSerializer *serializer) gdk_content_serializer_return_error (serializer, error); } +/** + * gdk_content_serialize_async: + * @stream: a #GOutputStream to write the serialized content to + * @mime_type: the mime type to serialize to + * @value: the content to serialize + * @io_priority: the io priority of the operation + * @cancellable: (nullable): optional #GCancellable object + * @callback: (scope async): callback to call when the operation is done + * @user_data: (closure): data to pass to the callback function + * + * Serialize content and write it to the given output stream, asynchronously. + * When the operation is finished, @callback will be called. You can then + * call gdk_content_serialize_finish() to get the result of the operation. + */ void gdk_content_serialize_async (GOutputStream *stream, const char *mime_type, @@ -509,6 +558,16 @@ gdk_content_serialize_async (GOutputStream *stream, user_data); } +/** + * gdk_content_serialize_finish: + * @result: the #GAsyncResult + * @error: return location for an error + * + * Finishes a content serialization operation. + * + * Returns: %TRUE if the operation was successful, %FALSE if an + * error occurred. In this case, @error is set + */ gboolean gdk_content_serialize_finish (GAsyncResult *result, GError **error) diff --git a/gdk/gdkcontentserializer.h b/gdk/gdkcontentserializer.h index 8b6dcf78ea..b2c34d4e37 100644 --- a/gdk/gdkcontentserializer.h +++ b/gdk/gdkcontentserializer.h @@ -32,8 +32,22 @@ G_BEGIN_DECLS #define GDK_CONTENT_SERIALIZER(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_CONTENT_SERIALIZER, GdkContentSerializer)) #define GDK_IS_CONTENT_SERIALIZER(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_CONTENT_SERIALIZER)) +/** + * GdkContentSerializer: + * + * Should not be accessed directly. + */ typedef struct _GdkContentSerializer GdkContentSerializer; +/** + * GdkContentSerializeFunc: + * @serializer: a #GdkContentSerializer + * + * The type of a function that can be registered with gdk_content_register_serializer(). + * When the function gets called to operate on content, it can call functions on the + * @serializer object to obtain the mime type, output stream, user data, etc. for its + * operation. + */ typedef void (* GdkContentSerializeFunc) (GdkContentSerializer *serializer); GDK_AVAILABLE_IN_3_94 -- 2.30.2